openapi: 3.0.0
info:
  title: MindsDB API
  description: >-
    OpenAPI Specification for MindsDB's REST API. Each API Endpoint corresponds
    to a specific SQL Statement e.g POST /model => CREATE MODEL
  version: 0.0.1
  contact:
    email: admin@mindsdb.com
  license:
    name: GNU General Public License v3.0
    url: 'https://github.com/mindsdb/mindsdb/blob/staging/LICENSE'
servers:
  - url: 'https://cloud.mindsdb.com/v1/api'
    description: MindsDB Production cloud server
  - url: 'http://alpha.mindsdb.com/v1/api'
    description: MindsDB Alpha cloud server
  - url: 'http://127.0.0.1/v1/api'
    description: MindsDB local deployments
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
paths:
  /databases:
    get:
      security:
        - ApiKeyAuth: []
      summary: Returns a list of database names.
      description: This endpoint retrieves all databases created by the user.
      responses:
        '200':
          description: A JSON array of database names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: 'database name'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    post:
      security:
        - ApiKeyAuth: []
      summary: Creates a new database connection.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                engine:
                  type: string
                user:
                  type: string
                password:
                  type: string
                host:
                  type: string
                port:
                  type: string
                database:
                  type: string
      responses:
        '201':
          description: Database was succesfully created
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    put:
      security:
        - ApiKeyAuth: []
      summary: Updates an existing database connection.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: string
                password:
                  type: string
                host:
                  type: string
                port:
                  type: string
                database:
                  type: string
      responses:
        '201':
          description: Database was succesfully updated
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/databases/{databaseName}':
    get:
      security:
        - ApiKeyAuth: []
      summary: Gets info about existing database.
      description: This endpoint retrieves a specific database info.
      parameters:
        - name: databaseName
          in: path
          description: databaseName to select
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with database informations
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Database not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    delete:
      security:
        - ApiKeyAuth: []
      summary: Deletes an existing database.
      description: This endpoint deletes a database connection.
      parameters:
        - name: databaseName
          in: path
          description: databaseName to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of database names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Database not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  /models:
    post:
      security:
        - ApiKeyAuth: []
      summary: This endpoint trains a new ML Model.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_name:
                  type: string
                  description: Name of the project where the model is created
                predictor_name:
                  type: string
                  description: Name of the model to be created.
                integration_name:
                  type: string
                  description: Name of the database integration created
                target_column:
                  type: string
                  description: Column to be predicted.
                query:
                  type: string
                  description: The SQL query to get the data
      responses:
        '200':
          description: Model training started
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    get:
      security:
        - ApiKeyAuth: []
      summary: Returns a list of models.
      description: This endpoint retrieves the status of all models.
      responses:
        '200':
          description: A JSON array of models names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: 'model name'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/models/{modelName}':
    get:
      security:
        - ApiKeyAuth: []
      summary: Gets info about specific model.
      description: This endpoint retrieves the status of a specific model.
      parameters:
        - name: modelName
          in: path
          description: The name of the model
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with database informations
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    post:
      security:
        - ApiKeyAuth: []
      summary: This endpoint fetches predictions from the model.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                model_name:
                  type: string
                  description: Name of the project where the model is created
                data:
                  type: string
                  description: The data for querying the model as SQL Statment or FILE
      responses:
        '200':
          description: Prediction data
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: str
    delete:
      security:
        - ApiKeyAuth: []
      summary: Deletes an existing model.
      description: This endpoint deletes a model.
      parameters:
        - name: modelName
          in: path
          description: modelName to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of database names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Database not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string                
  '/models/{modelName}/describe':
    get:
      security:
        - ApiKeyAuth: []
      summary: Describe a model
      description: This endpoint returns the attributes of a specific model.
      parameters:
        - name: modelName
          in: path
          description: The name of the model
          required: true
          schema:
            type: string
        - name: features
          in: query
          description: Include how the model encoded data info
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: A JSON object with model informations
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string